---
title: mdlTextConversion
summary: API reference for mdlTextConversion.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-08-21
library: SAIF.Business.Utilities
reference_type: embedded
---

# mdlTextConversion

A public module providing number-to-words conversion and sentence-case string formatting utilities. These operations are independent of the title-casing logic in `TitleCase` and serve specialized formatting needs (e.g. rendering numeric amounts as written English for legal or printed output, normalizing sentence-style display text). When `SAIF.Business.Utilities` is imported, `NumberToText` and `ToSentenceCase` become available directly on target values or as module-level functions. All members are public and shared; the module holds no state.

## Purpose
- Render whole numbers as English words (e.g. `1234` → `One Thousand Two Hundred Thirty Four `), suitable for written amounts on legal documents or printed forms.
- Normalize strings to sentence casing (first character upper, remainder lower) for consistent display presentation.
- Provide a clean API for magnitude-based numeric conversion with explicit error bounds and negative-number handling.

## Context
- Namespace: `SAIF.Business.Utilities`
- Assembly/package: `SAIF.Business.Utilities.dll`
- Module type: VB.NET `Public Module` (all members are either public functions or extension methods)

## Public members

| Member | Signature | Purpose |
| --- | --- | --- |
| `NumberToText` | `Public Function NumberToText(ByVal n As Long) As String` | Convert a whole number (long integer) to English words. Recursively decomposes by magnitude band (ones, tens, hundreds, thousands, millions, billions, trillions) and concatenates word forms. Returns space-delimited words with a trailing space. Throws `ApplicationException` if magnitude exceeds 999,999,999,999,999. Returns empty string for zero. |
| `ToSentenceCase` | `Public Function ToSentenceCase(ByVal Target As String) As String` (extension method) | Normalize a string to sentence casing: upper-case the first character, lower-case the remainder. Handles `Nothing` by returning `Nothing`; handles empty/single-character strings as edge cases. |

## Private implementation members (documented for control flow)

| Member | Signature | Role |
| --- | --- | --- |
| `RoundDown` | `Private Function (ByVal inValue As Long, ByVal inDivisor As Long) As Integer` | Integer magnitude division helper; used to extract the high-order band from a number (e.g., `RoundDown(1234, 1000)` → `1`, to identify "One Thousand"). |

## Behavioral notes
- **Magnitude decomposition**: `NumberToText` recursively processes numbers band-by-band (ones/teens, tens, hundreds, thousands, etc.). Each band from hundreds onward follows the pattern "emit `One <band>` for the leading 1, otherwise recurse and append band name". Band recursion continues for the remainder via `n Mod band` ([BR-016](../../business-rules.md#br-016-magnitude-band-decomposition)).
- **Zero and termination**: Returning empty string for zero ([BR-015](../../business-rules.md#br-015-zero-empty-string)) also serves as the recursion terminator when `n Mod band` becomes zero (e.g., `1000` terminates after "One Thousand" with no trailing "Zero").
- **Trailing space**: The output of `NumberToText` includes a trailing space (emitted by the ones/teens/unit branch). Consuming code may need to trim this for final display**.
- **Negative numbers**: Handled by prefixing `"Minus "` and recursing on the absolute value ([BR-014](../../business-rules.md#br-014-negative-number-rendering)). The recursive result is concatenated directly, so the trailing space from the absolute value is retained.
- **Magnitude limit**: Values > 999,999,999,999,999 throw `ApplicationException("Number too large to convert to text.  Limit is 999,999,999,999,999.")` ([BR-013](../../business-rules.md#br-013-number-magnitude-limit)). Callers must validate or catch this exception.
- **`StrConv` not used**: Unlike `TitleCaseExtensions.ToProperCase`, sentence casing is implemented directly (not via VB runtime functions) by manipulating the first character and calling `.ToLower()` on the remainder.
- **Recursion depth in `NumberToText`**: Depth is bounded by the magnitude bands (ones/tens/hundreds/thousands/millions/billions/trillions = ~7 levels maximum) but may increase if intermediate bands also recurse on their modulo remainder. For typical numbers, depth is modest*.

## Constraints and usage notes
- **Stateless**: All members are shared; calls are thread-safe.
- **Explicit output contract**: The output format (space-delimited words with trailing space) is stable for all inputs within the magnitude limit.
- **No locale/culture awareness**: The English word forms are hard-coded; no support for other languages or regional number formatting*.
- **No special handling for `Nothing`**: Calling `NumberToText` with a `Nothing` value is not applicable (VB `Nothing` for `Long` is `0`, which is valid and returns empty string). Calling `ToSentenceCase(Nothing)` explicitly returns `Nothing`*.
- **Actual callers within this repository**: `NumberToText` has no confirmed caller in the `SAIF.Business.Utilities` source or the consuming `SAIF.Business.View.Policy` project — its intended use (written amounts on legal/printed forms) is not observed in this codebase**.
- **`ToSentenceCase` callers**: Similarly, `ToSentenceCase` has no observed caller in this repository**.
- **`RoundDown` implementation**: Uses integer truncation to extract the magnitude band; the return type is `Integer` (32-bit signed), not `Long`. For inputs near the `Long.MaxValue`, overflow is theoretically possible (though the magnitude limit check in `NumberToText` prevents actual overflow)*.

## Related documentation
- [Index](../index.md)
- [TitleCase](TitleCase.md)
- [TitleCaseExtensions](TitleCaseExtensions.md)
- [Architecture](../../architecture.md)
- [Dependencies](../../dependencies.md)
- [Operations and processes](../../operations-processes.md)
- [Business rules](../../business-rules.md)

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts. Statements marked with ** could not be confirmed; treat as unknown until verified.

## Sources
- `SAIF.Business.Utilities/mdlTextConversion.vb`
- `SAIF.Business.Utilities/SAIF.Business.Utilities.vbproj`